Subject: More Spec Fixes

From: "Jack Sanders (8-444-4459)" <[email-masked]>
Date: Thu, 14 Apr 94 13:44:47 EDT

The following additional corrections are proposed to the CPI-C Spec.  Please
send any comments or questions to me at [email-masked].  Otherwise
the corrections will be added to the Spec as described.  Thansk to those
who have contributed corrections.

Regards,
Jack
---------------------------------------------------------------------------
Change 10 - Receive call return codes for FDX conversations

Rationale: Correct parenthetical errors

Fix: In the list of return codes for the Receive call for full-duplex
conversations, replace

  * CM_PROGRAM_ERROR_NO_TRUNC (half-duplex conversations only)
  * CM_PROGRAM_ERROR_TRUNC (basic half-duplex conversations only)

with

  * CM_PROGRAM_ERROR_NO_TRUNC
  * CM_PROGRAM_ERROR_TRUNC (basic conversations only)

-----------------------------------------------------------------------
Change 11 - Add detail to Begin-Transaction parameter of the
TP-Begin-Dialogue indication

Rationale: If Begin-Transaction is set to true, the program is notified
by a status_received value of CM_JOIN_TRANSACTION.

Fix: in the OSI TP mapping appendix, for both HDX and FDX conversations,
for the TP-Begin-Dialogue indication mapping, replace

 Begin-Transaction              * (through a resource recovery interface)

with

 Begin-Transaction
    true                        Completes an outstanding
                                   CMRCV - Receive
                                and maps to
                                   status_received = CM_JOIN_TRANSACTION;
                                (also available through a resource
                                  recovery interface)
    false                       * (through a resource recovery interface)

-----------------------------------------------------------------------
Change 12 - Joining a Transaction clarification

Rationale: If the superior is not in transaction when it issues an
Allocate, Confirm, Include_Partner_In_Transaction, Prepare,
Prepare_To_Receive, Receive, Send_Data or Send_Error call, the
begin_transaction characteristic is ignored, and the subordinate
is not asked to join a transaction.

Fix:  Clarify the above in section 2.14.6 and add a usage note to the
Begin_Transaction call.

-----------------------------------------------------------------------
Change 13 - Mapping to Begin-Transaction clarification

Rationale:  For a conversation using unchained transactions and an OSI TP
CRM, if begin_transaction = CM_BEGIN_IMPLICIT and the conversation's
context is in transaction when a program issues an Allocate call, the
Begin-Transaction parameter of the TP-Begin-Dialogue request
is set to true; otherwise it is set to false.

Fix:  In the mapping-to-OSI-TP sections D.2.2 and D.3, add notes to the
Allocate mapping tables to indicate the above.

-----------------------------------------------------------------------
Change 14 - Callback updates

Rationale:

Background
==========
  1) Set_Queue_Callback_Function (CMSQCF) requires that the program
     pass in a routine as a parameter, but not every programming
     language can support this type of parameter passing.
  >> Proposed solution:  state the call is currently supported by C
     only.

  2) The note for the UNIX environment, suggesting that SIGUSR1 or
     SIGUSR2 be used as a mechanism for invoking callback function,
     is overstating.  Other mechanisms, such as threads, can be used.
  >> Proposed solution:  remove the description of use of callback_info
     for the UNIX environment.

  3) CPI-C cannot tell if the program is an OS/2 or PM application.
  >> Proposed solution:  remove the note for PM.

  4) The usage note 9 addresses program portability within the like
     systems.  Portability can be improved by defining a common
     interface for the callback function.
  >> Proposed solution:
     a) define two input parameters, user_field and call_ID, for the
        callback_function
     b) remove callback_info from CMSQCF
     c) state an exceptional case; namely, Windows

Proposed Change Pages
=====================
A) Set_Queue_Callback_Function call
   - remove callback_info from the list of parameters

   - add a new usage note:
|    1. Because of requiring support of passing a callback function
|       as a parameter, the call is supported by the C programming
|       language only.

   - consolidate the original note 8 and 9 as follows:
|    9. A callback function is a user-defined routine and has two
|       input parameters, user_field and call_ID.  It is used to
|       handle completion of an outstanding operation.

        If a callback function is set for a conversation queue, the
        function is invoked when an outstanding operation on the queue
        completes.  The user field, as specified by the program,
|       and call ID for the completed operation can then be passed
        to the callback function.

        Note: An exception is the Microsoft Windows(TM) environment.
        The callback_function parameter is ignored in Windows, and
        the user_field parameter contains a pointer pointing to
        a structure of type MSG, as defined by Windows.  The structure
        contains at least a window handle, message number, word value,
        and doubleword value.  When an outstanding operation completes,
        CPI Communications will use these fields as arguments to call
        the Windows PostMessage function.
|       Upon catching the message, the program can then invoke
|       a routine (taking the word value and doubleword value as
|       input) to handle the completion of the outstanding operation.

B) Chapter2. 2.10.2.2 Using Callback Function
   - delete the first "callback information"

   - replace the second "callback information" with "call ID"

C) Appendix A. Table 15. Variable Types and Lengths
   - delete callback_info

   - change callback_function to:
     ---------------------------------------------------------------------
     Variable           Variable Type   Character Set   Length
     ---------------------------------------------------------------------
|    callback_function  pointer*        N/A             system-dependent*
     ---------------------------------------------------------------------
     Note:
|    *  callback_function specifies a pointer to a routine and is
|       supported by the C programming language only.  Its length
|       depends on the C compiler.

D) Appendix E. Pseudonym Files
   - delete callback_info in all the files

   - delete callback_function and CMSQCF in all the files except
     the one for C

   - change CM_ENTRY cmsqcf in the C pseudonym file to the following:
     CM_ENTRY cmsqcf (unsigned char CM_PTR,        /* conversation_ID    */
                      CM_CONVERSATION_QUEUE CMPTR, /* conversation_queue */
|                     void CM_PTR,                 /* callback_function  */
                      unsigned char CM_PTR,        /* user_field         */
                      CM_RETURN_CODE CMPTR);       /* return_code        */